Individual Project - Multi-Agent Email Forensics System

Overview

The Multi-Agent Email Forensics System is an intelligent agent-based solution for automated security analysis of email communications. The system employs four specialized autonomous agents working in a coordinated pipeline to discover, analyze, visualize, and report on potential security threats.

Key Capabilities

Automated Threat Detection: Identifies suspicious emails based on keywords, temporal patterns, source analysis, and volume anomalies
Multi-Strategy Analysis: Employs four parallel detection strategies for comprehensive coverage
Visual Analytics: Generates 8 different visualization types for pattern recognition
Comprehensive Reporting: Produces both technical (text) and executive (HTML) reports
Forensic Quality: Designed following digital forensics best practices (NIST SP 800-86)

Specialized Agents

Tests (100% Passing)

Visualizations

Pipeline Stages

System Architecture

The system implements a cooperative multi-agent architecture where four specialized agents work sequentially in a pipeline:

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌────────────────┐
│  Discovery      │────▶│  Analysis    │────▶│  Dashboard      │────▶│  Report        │
│  Agent          │     │  Agent       │     │  Agent          │     │  Agent         │
└─────────────────┘     └──────────────┘     └─────────────────┘     └────────────────┘
        │                       │                      │                       │
        ▼                       ▼                      ▼                       ▼
   Email Files            Findings List         Visualizations          Reports

1. DiscoveryAgent

Role: Autonomous data acquisition

Locates email files and parses them into structured objects

Pattern: Repository

2. AnalysisAgent

Role: Threat detection

Applies 4 parallel detection strategies

Pattern: Strategy

3. DashboardAgent

Role: Visual analytics

Creates 8 visualization types

Pattern: Factory

4. ReportAgent

Role: Report generation

Produces text and HTML reports

Pattern: Template Method

Analysis Results & Visualizations

Summary Statistics

Email Forensics Summary Statistics - Total emails, suspicious emails, external communications, and findings

Key Visualizations

Activity Heatmap - Email patterns by hour and day

Severity Distribution - Classification of findings

Word Cloud - Common terms in suspicious emails

Six-Stage Pipeline

Stage 1: Data Generation

EnhancedEmailGenerator creates 50 test emails (30% suspicious, 70% normal) with realistic subjects, timestamps, and sender domains.

Output: Email files in output/emails/

Stage 2: Discovery

DiscoveryAgent autonomously locates and loads emails, parsing structure (ID, Subject, From, To, Date, Content) into SimpleEmail objects.

Output: List of SimpleEmail objects

Stage 3: Analysis

AnalysisAgent applies four parallel detection strategies:

Keyword Analysis: Scans for 21 suspicious terms (urgent, confidential, bitcoin, phishing, etc.)
Temporal Analysis: Flags after-hours emails (outside 8 AM - 6 PM)
Source Analysis: Identifies external domain communications
Volume Analysis: Detects anomalous sending patterns

Output: List of Finding objects with severity classification (High/Medium/Low)

Stage 4: Visualization

DashboardAgent generates 8 visualizations using matplotlib, seaborn, and wordcloud:

Summary statistics chart
Email distribution pie chart
Hourly activity histogram
Subject word cloud
Activity timeline
Day-hour heatmap
Network analysis
Severity distribution

Output: PNG files in output/visualizations/

Stage 5: Reporting

ReportAgent consolidates results using Jinja2 templates into text and HTML formats with embedded visualizations.

Output: forensics_report.html and forensics_report.txt in output/reports/

Stage 6: UML Documentation

Auto-generates PlantUML class and sequence diagrams documenting system architecture.

Output: Documentation in output/uml_documentation/

Technical Implementation

Data Models

SimpleEmail: Email dataclass with fields id, subject, sender, recipient, date, content, file_path

Methods:

is_suspicious() - Checks for 21 suspicious keywords
is_after_hours() - Detects outside business hours (8 AM - 6 PM)
is_external() - Checks if sender is from external domain

Finding: Investigation finding with finding_type, description, email_id, severity, timestamp

Dependencies

Data: pandas ≥1.5.0, numpy ≥1.23.0
Visualization: matplotlib ≥3.6.0, seaborn ≥0.12.0, wordcloud ≥1.9.0
Templating: jinja2 ≥3.1.0
Testing: pytest ≥7.2.0, pytest-cov ≥4.0.0

Testing & Validation

29 tests, 100% passing:

25 unit tests (individual methods)
3 integration tests (agent coordination)
1 end-to-end test (complete pipeline)

Personal Reflection

Building this multi-agent system from scratch revealed the practical value of autonomous, specialized agents working in coordinated pipelines. The separation of concerns between discovery, analysis, visualization, and reporting made the system easier to develop, test, and maintain.

Implementing four detection strategies taught me that effective security analysis requires multiple perspectives. Keyword detection alone misses after-hours anomalies, while temporal analysis misses sophisticated phishing from normal hours. The comprehensive testing (29 tests, 100% passing) caught integration bugs early, particularly in data flow between agents.

This project connected theoretical concepts about agent architectures (Wooldridge, 2009) with practical concerns like error handling and user experience. Generating professional visualizations taught me that intelligent systems must present results in accessible formats for non-technical stakeholders.

← Back to Intelligent Agents Portfolio